远程升级OTA最佳实践

物联网平台通用OTA设备侧使用说明

通用远程升级功能，包括模组升级和MCU应用升级两类，待升级的设备通过HTTP协议RESTful标准格式与物联网平台进行数据交互以完成升级。

南向设备目前所需的RESTful API一共有三类：检测任务、拉取文件、上报状态，其中拉取文件包括校验TOKEN和获取文件两个API。

本页内容介绍的是API的使用以及通过postman模拟器测试拉取固件的过程。

本文档适用于使用物联网平台进行通用OTA功能操作的设备侧操作相关人员。

1. 鉴权参数

此处采用Python来计算产品Authorization,实际操作时更改产品ID和Product Secret即可,具体过程参考API鉴权，Python代码。

计算出来的鉴权参数为：

version=2018-10-31&res=products%2F245528&et=7559008892&method=sha1&sign=TPllhakDDnUV90epLnOqpj6aWqI%3D

2. 检测任务

http://{{ota.heclouds.com}}/ota/south/check?dev_id=527776559&manuf=102&model=10201&type=2&version=V1&cdn=false

Headers的参数Authorization：value为计算出来的产品token。

manuf=102&model=10201这两个参数参考下面的表格。 dev_id=527776559修改为需要升级的设备id。 其他参数不改变。

SOTA的厂商、模组对照表

FOTA的厂商、模组对照表

示例的请求响应的代码如下:

{
    "errno": 0,
    "error": "succ",
    "data": {
        "target": "V1",
        "token": "ota_iF0hnXrq2CxLrP8vZ39l",
        "size": 22,
        "md5": "ad2f4e4ea2a27eace7e4913139f8f01a",
        "signal": 10,
        "power": 50,
        "retry": 0,
        "interval": 0,
        "type": 1
    }
}

3. 校验TOKEN

校验TOKEN使用说明和响应信息请参考OTA-SDK说明文档。

http://{{ota.heclouds.com}}/ota/south/download/ota_iF0hnXrq2CxLrP8vZ39l/check?dev_id=527776559

Headers的参数Authorization：value为上面计算出来的产品token。

Body内容为：

{
    "result": 201
}

result:

101:升级包下载成功 102:下载失败,空间不足 103:下载失败,内存溢出 104:下载失败,下载请求超时 105:下载失败,电量不足 106:下载失败,信号不良 107:下载失败,未知异常 201:升级成功 202:升级失败,电量不足 203:升级失败,内存溢出 204:升级失败,版本不一致 205:升级失败,md5校验失败 206:升级失败,未知异常

error:

0:上报状态成功 1:上报状态失败，token鉴权失败 2:上报状态失败，状态码有误 20:上报状态失败，升级任务已经完成 21:无效的操作 22:上报状态失败，升级任务已被取消 24:请求内容result错误

说明

dev_id=527776559修改为需要升级的设备id。 ota_iF0hnXrq2CxLrP8vZ39l为鉴权参数步骤获取到的任务token。 其他参数不改变。

需要替换成实际地址

4. 拉取文件

拉取文件使用说明和响应信息如下。

http://{{ota.heclouds.com}}/ota/south/download/ota_iF0hnXrq2CxLrP8vZ39l

ota_iF0hnXrq2CxLrP8vZ39l为鉴权参数步骤获取到的任务token，其他参数不改变。 可以拉取整个文件。

也可以拉取部分文件。

头部Range字段解释：

Range: bytes={start}-{end}

目前只支持如下几种模式

(1) Range: bytes={start}-，获取第{start}+1个字节到最后的数据
例如：Range: bytes=0-，获取所有数据;
Range: bytes=2-，获取第3个数据到最后1个数据;
注意：如果{start}>=文件总长度，则默认{start}=0 。

(2) Range: bytes={start}-{end}，获取第{start}+1个字节到第{end}+1个字节 例如：Range: bytes=0-99，获取前100个字节; 注意：若{end}>=文件总长度len，则默认end=len-1; 若{start}>{end}，start被设置为0。

(3) Range: bytes=-{end}，获取最后end个字节数据 例如：Range: bytes=-100，获取最后100个字节数据； 注意：如果{end}>文件总长度len，则默认end=len（获取所有文件）。

分片状态码

分片返回的状态码：206 不分片返回的状态码：200

5. 上报状态

上报状态使用说明和响应信息如下。

http://{{ota.heclouds.com}}/ota/south/report?dev_id=527776559&token=ota_iF0hnXrq2CxLrP8vZ39l

Headers的参数Authorization：value为上面计算出来的产品token。

Body内容为：

{
    "result": 201
}

result:

101:升级包下载成功 102:下载失败,空间不足 103:下载失败,内存溢出 104:下载失败,下载请求超时 105:下载失败,电量不足 106:下载失败,信号不良 107:下载失败,未知异常 201:升级成功 202:升级失败,电量不足 203:升级失败,内存溢出 204:升级失败,版本不一致 205:升级失败,md5校验失败 206:升级失败,未知异常

error:

0:上报状态成功 1:上报状态失败，token鉴权失败 2:上报状态失败，状态码有误 20:上报状态失败，升级任务已经完成 21:无效的操作 22:上报状态失败，升级任务已被取消 24:请求内容result错误

说明

dev_id=527776559修改为需要升级的设备id。 ota_iF0hnXrq2CxLrP8vZ39l为鉴权参数步骤获取到的任务token。 其他参数不改变。

上报升级成功状态后，平台会显示任务状态为完成。